<html><head> <meta http-equiv="Pragma" content="no-cache"/> <meta
http-equiv="Cache-Control" content="no-cache"/> <meta
http-equiv="Expires" content="0" /> <title>PyMOL Web Services
</title> </head> <body>
<h3>PyMOL Web Services</h3>

<ul>
<li>A summary of <a href="./content/summary.html" target="_blank">changes
since the last update</a>.</li>

<li>An overview of the <a href="./content/server.html" target="_blank">PyMOL HTTP server</a>.</li>

<li>A compact <a href="./content/reference.html" target=_blank>API
reference</a> with names and parameters for all exposed methods.</li>

<li>Explanation of how <a href="./content/pwg.html" target="_blank">PWG
files<a/> are used to launch PyMOL with its HTTP Server.</a> </li>

<li>A discussion of the various <a href="./content/requests.html"
target="_blank">request generation methods</a>.</li>

<li>Coverage of the <a href="./content/SOP.html" target="_blank">same origin
policy</a> and how it impacts this interface.</li>

<li>Tips on <a href="./content/running.html" target="_blank">running</a> the
sample applications below.</li>

</ul>

<p><b>Sample Mini-Applications</b></p>

<p>These sample applications will introduce you to the concepts needed
to develop your own PyMOL web applications.  They gradually move from
simple to complex, demonstrating the various ways of integrating PyMOL
into your own web infrastructure.  If nothing happens when you click
these links, please review the section on <a href="./content/running.html"
target="_blank">running</a> them and consult the README.TXT file
accompanying the distribution.</p>

<ul><li><p><b>Same Origin</b></p>

<p>Where PyMOL is the only web server, and it serves all the ordinary
http content as well as handling PyMOL-specific method requests.</p>

<ul>

<li><a name=sample01> 
<!-- TJ NOTE: anchor needs to be within the li to prevent formatting issues -->
<p><a href="./sample01/start.pwg">Sample 01</a>: is a simple
validation application demonstrating the simplest-possible use case:
static HTTP links targeting a separate frame.  This application
provides basic documentation for and validation of the core PyMOL
web services API, but is probably not an example you should follow in
developing your own applications.</p></li>


<li><a name=sample02><p><a href="./sample02/start.pwg">Sample 02</a>: is a
slightly more sophisticated application which makes use of JavaScript
to lighten the burden on the web developer.  The response
from PyMOL is directed to an embedded IFRAME on the page.  Note that
this approach is limited to issuing a single PyMOL request per DOM
event.  For this reason, we do not recommend using this approach
except for trivial applications.</p></li>

<li><a name=sample03>
<p><a href="./sample03/start.pwg">Sample 03</a>: works much like
Sample 02, but we have added the important extra convenience of a
command queue bound to the IFRAME.  This makes it possible to issue
multiple PyMOL commands from JavaScript in response to a single DOM
event.  This application illustrates our recommended method for
developing simple PyMOL web applications if minimal use of
JavaScript is desired.</p></li>

<li><a name=sample04>
<p><a href="./sample04/start.pwg">Sample 04</a>: is a more complex
same-origin structure table application which offers the user a series
of buttons for toggling structures on and off, with various
representations.</p></li>

<li><a name=sample05>
<p><a href="./sample05/start.pwg">Sample 05</a> is a same-origin
demonstration application which uses XmlHttpRequest objects to both
make requests and receive JSON object responses back from PyMOL in a
synchronous fashion.  Note that this synchronous remote-procedure-call
behavior is only possible under the same-origin scenario.</p></li>

<li><a name=sample06>
<p><a href="./sample06/start.pwg">Sample 06</a>: introduces our
JavaScript API for PyMOL, which is based on wrapping XMLHttpRequests
underneath JavaScript objects which expose an API for PyMOL very
similar to that available from within Python.  This sample runs
synchronously. Please note that the pymol.js implementation included
in this deliverable is preliminary and potentially subject to change.
However, this will likely be the optimal approach for developing web-based
PyMOL applications.</p></li>

<li><a name=sample07>
<p><a href="./sample07/start.pwg">Sample 07</a>:
shows how an HTML FORM can be used with PyMOL Web Services.
This allows one to use buttons, checkboxes and other INPUT elements
of a FORM to deliver commands to PyMOL.  It also shows how a
file can be uploaded to PyMOL.</p></li>
</li>

<li><a name=sample08>
<p><a href="./sample08/start.pwg">Sample 08</a>: demonstrates how you
can use the buffering features of the PyMOL JavaScript API to
consolidate many method calls into a single request and thus achieve
better performance and reliability.</p></li>

</ul>

</li>
<li><p><b>Multi Origin (Cross-Domain)</b></p>

<p>Where web content is served from a remote web server and the web
broswer is responsible for sending requests to a local PyMOL instance
which operates its own web (HTTP) server for processing PyMOL-specific
method requests.</p> <ul>

<li><a name=sample11>
<p><a target="_blank" href="./sample11/index.html">Sample 11</a>
introduces the multi-origin scenario, where the host and port number
of the PyMOL server instance must be explicitly specified in the web
page.</p></li>

<li><a name=sample12>
<p><a target="_blank" href="./sample12/index.html">Sample 12</a> shows
how a multi-origin application works using our JavaScript API.  In the
multi-origin scenario everything happens asynchronously, and so
callbacks must be employed if your script is to act upon results
obtained from PyMOL requests.</p></li>

<li><a name=sample13>
<p><a target="_blank" href="./sample13/index.html">Sample 13</a>
shows how you can instead use jQuery with the JSONP hack
to do multi-origin scripting.</p></li>

<li><a name=sample14>
<p><a target="_blank" href="./sample14/index.html">Sample 14</a>
shows how you can use the buffering features of our JavaScript API to
avoid problems with out-of-order method execution.</p></li>

<li><a name=sample15>
<p><a target="_blank" href="./sample15/index.html">Sample 15</a> shows
how you can use IFRAMEs to launch on or more PyMOL instances manually
(at the user's request), instead of having it launch automatically, as
in the previous examples.</p></li>

<li><a name=sample16>
<p><a target="_blank" href="./sample16/index.html">Sample 16</a> covers the API functions for controlling buffering and explains how you can get the current buffer as a JSON-encoded string or URL for use with a separate JavaScript framework such as jQuery.</p></li>
</ul>

<p>Hopefully you now have enough information to start developing your
own web content and applications which integrate PyMOL using the web
services interface!</p>

<p>The code for the applications above is located inside a series of folders located at:
<pre>$PYMOL_PATH/modules/web/examples/sample*</pre></p>

</body>
</html>
